#ifndef _MOTOR_PID_H__
#define _MOTOR_PID_H__


/**
  * @brief  PID控制句柄
  */
typedef struct {
  float Kp, Ki, Kd;   /*!< PID参数  */
  int Imax;           /*!< I限幅值  */
  float err;          /*!< 当前误差  */
  float err_pre;      /*!< 上次误差  */
  float err_sum;      /*!< 误差累积  */
  float err_dif;      /*!< 误差差值  */
  float dt;           /*!< 时间间隔  */
} PID_HandleTypeDef;

//-----------------------------------------------	

/**
 * @if Eng
 * @brief Initializes PID controller structure 
 * @param hpid - Pointer to PID_HandleTypeDef structure
 * @param Kp - Proportional gain 
 * @param Ki - Integral gain 
 * @param Kd - Derivative gain 
 * @param dt - Control loop time step (seconds)
 * @result PID controller is initialized with specified parameters 
 * @else 
 * @brief 初始化PID控制器结构体 
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param Kp - 比例增益 
 * @param Ki - 积分增益
 * @param Kd - 微分增益
 * @param dt - 控制循环时间步长(秒)
 * @result PID控制器被初始化为指定参数 
 * @endif 
 */
void PID_Init(PID_HandleTypeDef *hpid, float Kp, float Ki, float Kd, float dt);

/**
 * @if Eng
 * @brief Computes full PID control output
 * @param hpid - Pointer to PID_HandleTypeDef structure 
 * @param err - Current error value (setpoint - actual)
 * @return PID control output value 
 * @else 
 * @brief 计算完整的PID控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值(设定值-实际值)
 * @return PID控制输出值 
 * @endif 
 */
float PID_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng 
 * @brief Computes PD (Proportional-Derivative) control output 
 * @param hpid - Pointer to PID_HandleTypeDef structure
 * @param err - Current error value 
 * @return PD control output value
 * @else
 * @brief 计算PD(比例-微分)控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值 
 * @return PD控制输出值 
 * @endif 
 */
float PD_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng 
 * @brief Computes PI (Proportional-Integral) control output 
 * @param hpid - Pointer to PID_HandleTypeDef structure
 * @param err - Current error value 
 * @return PI control output value 
 * @else 
 * @brief 计算PI(比例-积分)控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值 
 * @return PI控制输出值 
 * @endif 
 */
float PI_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng 
 * @brief Computes P (Proportional) control output
 * @param hpid - Pointer to PID_HandleTypeDef structure 
 * @param err - Current error value
 * @return P control output value
 * @else
 * @brief 计算P(比例)控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值 
 * @return P控制输出值 
 * @endif 
 */
float P_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng 
 * @brief Computes I (Integral) control output
 * @param hpid - Pointer to PID_HandleTypeDef structure 
 * @param err - Current error value 
 * @return I control output value 
 * @else 
 * @brief 计算I(积分)控制输出 
 * @param hpid - 指向PID_HandleTypeDef结构体的指针
 * @param err - 当前误差值
 * @return I控制输出值 
 * @endif 
 */
float I_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng 
 * @brief Computes D (Derivative) control output
 * @param hpid - Pointer to PID_HandleTypeDef structure 
 * @param err - Current error value
 * @return D control output value
 * @else
 * @brief 计算D(微分)控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值 
 * @return D控制输出值 
 * @endif 
 */
float D_Base_Cale(PID_HandleTypeDef *hpid, float err);

/**
 * @if Eng
 * @brief Computes first-order filtered P control output 
 * @param hpid - Pointer to PID_HandleTypeDef structure
 * @param err - Current error value 
 * @param filter_coef - Filter coefficient (0.0 to 1.0)
 * @return Filtered P control output value
 * @else
 * @brief 计算一阶滤波的P控制输出
 * @param hpid - 指向PID_HandleTypeDef结构体的指针 
 * @param err - 当前误差值 
 * @param filter_coef - 滤波系数(0.0到1.0)
 * @return 滤波后的P控制输出值 
 * @endif 
 */
float P_Filter_FO(PID_HandleTypeDef *hpid, float err, float filter_coef);

/**
 * @if Eng 
 * @brief Limits a value to specified range 
 * @param val - Pointer to value to limit (input/output)
 * @param vmin - Minimum allowed value
 * @param vmax - Maximum allowed value
 * @result Value is clamped to [vmin, vmax] range
 * @else
 * @brief 将值限制在指定范围内 
 * @param val - 要限制的值的指针(输入/输出)
 * @param vmin - 允许的最小值
 * @param vmax - 允许的最大值 
 * @result 值被限制在[vmin, vmax]范围内 
 * @endif 
 */
void PID_Limit(float *val, float vmin, float vmax);

/**
 * @if Eng
 * @brief Computes quadratic function output 
 * @param x - Input value 
 * @param a - Quadratic coefficient 
 * @param b - Linear coefficient 
 * @param c - Constant term 
 * @return Result of quadratic function (ax² + bx + c)
 * @else
 * @brief 计算二次函数输出 
 * @param x - 输入值
 * @param a - 二次项系数
 * @param b - 一次项系数
 * @param c - 常数项 
 * @return 二次函数结果(ax² + bx + c)
 * @endif 
 */
float PID_Quadratic_Cale(float x, float a, float b, float c);

/**
 * @if Eng
 * @brief Maps a value from one range to another 
 * @param x - Input value to map
 * @param in_min - Minimum of input range 
 * @param in_max - Maximum of input range
 * @param out_min - Minimum of output range 
 * @param out_max - Maximum of output range
 * @return Value mapped to output range
 * @else
 * @brief 将值从一个范围映射到另一个范围
 * @param x - 要映射的输入值
 * @param in_min - 输入范围的最小值
 * @param in_max - 输入范围的最大值
 * @param out_min - 输出范围的最小值
 * @param out_max - 输出范围的最大值
 * @return 映射到输出范围的值
 * @endif 
 */
float PID_Mapping(float x, float in_min, float in_max, float out_min, float out_max);

#endif
